

    \filetitle{estimate}{Estimate model parameters by optimising selected objective function}{model/estimate}

	\paragraph{Syntax}

Input arguments marked with a \texttt{\textasciitilde{}} (tilde) sign
may be omitted.

\begin{verbatim}
[PEst,Pos,Cov,Hess,M,V,Delta,PDelta] = estimate(M,D,Range,Est,~Spr,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{M} {[} model {]} - Model object with single parameterization.
\item
  \texttt{D} {[} struct \textbar{} cell {]} - Input database or datapack
  from which the measurement variables will be taken.
\item
  \texttt{Range} {[} struct \textbar{} char {]} - Date range on which
  the data likelihood will be evaluated.
\item
  \texttt{Est} {[} struct {]} - Database with the list of paremeters
  that will be estimated, and the parameter prior specifications (see
  below).
\item
  \texttt{\textasciitilde{}SPr} {[} systempriors \textbar{} \emph{empty}
  {]} - System priors object,
  \href{systempriors/Contents}{\texttt{systempriors}}; may be omitted.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{PEst} {[} struct {]} - Database with point estimates of
  requested parameters.
\item
  \texttt{Pos} {[} poster {]} - Posterior,
  \href{poster/Contents}{\texttt{poster}}, object; this object also
  gives you access to the value of the objective function at optimum or
  at any point in the parameter space, see the
  \href{poster/eval}{\texttt{poster/eval}} function.
\item
  \texttt{Cov} {[} numeric {]} - Approximate covariance matrix for the
  estimates of parameters with slack bounds based on the asymptotic
  Fisher information matrix (not on the Hessian returned from the
  optimization routine).
\item
  \texttt{Hess} {[} cell {]} - \texttt{Hess\{1\}} is the total hessian
  of the objective function; \texttt{Hess\{2\}} is the contributions of
  the priors to the hessian.
\item
  \texttt{M} {[} model {]} - Model object solved with the estimated
  parameters (including out-of-likelihood parameters and common variance
  factor).
\end{itemize}

The remaining three output arguments, \texttt{V}, \texttt{Delta},
\texttt{PDelta}, are the same as the
\href{model/loglik}{\texttt{model/loglik}} output arguments of the same
names.

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}chkSstate=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} \textbar{} cell {]} -
  Check steady state in each iteration; works only in non-linear models.
\item
  \texttt{\textquotesingle{}evalFrfPriors=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - In each
  iteration, evaluate frequency response function prior density, and
  include it to the overall objective function to be optimised.
\item
  \texttt{\textquotesingle{}evalLik=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - In each
  iteration, evaluate likelihood (or another data based criterion), and
  include it to the overall objective function to be optimised.
\item
  \texttt{\textquotesingle{}evalPPriors=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - In each
  iteration, evaluate parameter prior density, and include it to the
  overall objective function to be optimised.
\item
  \texttt{\textquotesingle{}evalSPriors=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - In each
  iteration, evaluate system prior density, and include it to the
  overall objective function to be optimised.
\item
  \texttt{\textquotesingle{}filter=\textquotesingle{}} {[} cell
  \textbar{} \emph{empty} {]} - Cell array of options that will be
  passed on to the Kalman filter including the type of objective
  function; see help on \href{model/filter}{\texttt{model/filter}} for
  the options available.
\item
  \texttt{\textquotesingle{}initVal=\textquotesingle{}} {[}
  \texttt{model} \textbar{} \emph{\texttt{struct}} \textbar{} struct {]}
  - If \texttt{struct} use the values in the input struct \texttt{Est}
  to start the iteration; if \texttt{model} use the currently assigned
  parameter values in the input model, \texttt{M}.
\item
  \texttt{\textquotesingle{}maxIter=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{500}} {]} - Maximum number of iterations
  allowed.
\item
  \texttt{\textquotesingle{}maxFunEvals=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{2000}} {]} - Maximum number of objective
  function calls allowed.
\item
  \texttt{\textquotesingle{}noSolution=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}error\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}penalty\textquotesingle{}} \textbar{}
  numeric {]} - Specifies what happens if solution or steady state fails
  to solve in an iteration:
  \texttt{\textquotesingle{}error=\textquotesingle{}} stops the
  execution with an error message,
  \texttt{\textquotesingle{}penalty=\textquotesingle{}} returns an
  extreme value, \texttt{1e10}, back into the minimization routine; or a
  user-supplied penalty can be specified as a numeric scalar greater
  than \texttt{1e10}.
\item
  \texttt{\textquotesingle{}optimSet=\textquotesingle{}} {[} cell
  \textbar{} \emph{empty} {]} - Cell array used to create the
  Optimization Toolbox options structure; works only with the option
  \texttt{\textquotesingle{}optimiser=\textquotesingle{}}
  \texttt{\textquotesingle{}default\textquotesingle{}}.
\item
  \texttt{\textquotesingle{}solve=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} \textbar{} cellstr {]}
  - Re-compute solution in each iteration; you can specify a cell array
  with options for the \texttt{solve} function.
\item
  \texttt{\textquotesingle{}optimiser=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}default\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}pso\textquotesingle{}} \textbar{} cell
  \textbar{} function\_handle {]} - Minimiz ation procedure.

  \begin{itemize}
  \item
    \texttt{\textquotesingle{}default\textquotesingle{}}: The
    Optimization Toolbox function \texttt{fminunc} or \texttt{fmincon}
    will be called depending on the presence or absence of lower and/or
    upper bounds.
  \item
    \texttt{\textquotesingle{}alps\textquotesingle{}}: The age layer
    population structure evolutionary algorithm will be used. See
    irisoptim.alps help for more information.
  \item
    \texttt{\textquotesingle{}pso\textquotesingle{}}: The particle swarm
    optimizer will be called. See the irisoptim.pso help for more
    information.
  \item
    function\_handle or cell: Enter a function handle to your own
    optimization procedure, or a cell array with a function handle and
    additional input arguments (see below).
  \end{itemize}
\item
  \texttt{\textquotesingle{}sstate=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} \textbar{} cell \textbar{}
  function\_handle {]} - Re-compute steady state in each iteration; you
  can specify a cell array with options for the \texttt{sstate}
  function, or a function handle whose behaviour is described below.
\item
  \texttt{\textquotesingle{}tolFun=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1e-6}} {]} - Termination tolerance on the
  objective function.
\item
  \texttt{\textquotesingle{}tolX=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1e-6}} {]} - Termination tolerance on the
  estimated parameters.
\end{itemize}

\paragraph{Description}

The parameters that are to be estimated are specified in the input
parameter estimation database, \texttt{E} in which you can provide the
following specifications for each parameter:

\begin{verbatim}
E.parameter_name = { start, lower, upper, logpriorFunc };
\end{verbatim}

where \texttt{start} is the value from which the numerical optimization
will start, \texttt{lower} is the lower bound, \texttt{upper} is the
upper bound, and \texttt{logpriorFunc} is a function handle expected to
return the log of the prior density. You can use the
\href{logdist/Contents}{\texttt{logdist}} package to create function
handles for some of the basic prior distributions.

You can use \texttt{NaN} for \texttt{start} if you wish to use the value
currently assigned in the model object. You can use \texttt{-Inf} and
\texttt{Inf} for the bounds, or leave the bounds empty or not specify
them at all. You can leave the prior distribution empty or not specify
it at all.

\subparagraph{Estimating nonlinear
models}

By default, only the first-order solution, but not the steady state is
updated (recomputed) in each iteration before the likelihood is
evaluated. This behavior is controled by two options,
\texttt{\textquotesingle{}solve=\textquotesingle{}} (\texttt{true} by
default) and \texttt{\textquotesingle{}sstate=\textquotesingle{}}
(\texttt{false} by default). If some of the estimated parameters do
affect the steady state of the model, the option
'\texttt{sstate=\textquotesingle{}} needs to be set to \texttt{true} or
to a cell array with steady-state options, as in the function
\href{model/sstate}{\texttt{sstate}}, otherwise the results will be
groslly inaccurate or a valid first-order solution will be impossible to
find.

When steady state is recomputed in each iteration, you may also want to
use the option \texttt{\textquotesingle{}chksstate=\textquotesingle{}}
to require that a steady-state check for all model equations be
performed.

\subparagraph{User-supplied optimization (minimization)
routine}

You can supply a function handle to your own minimization routine
through the option
\texttt{\textquotesingle{}optimiser=\textquotesingle{}}. This routine
will be used instead of the Optim Tbx's \texttt{fminunc} or
\texttt{fmincon} functions. The user-supplied function is expected to
take at least five input arguments and return three output arguments:

\begin{verbatim}
[PEst,ObjEst,Hess] = yourminfunc(F,P0,PLow,PHigh,OptimSet)
\end{verbatim}

with the following input arguments:

\begin{itemize}
\tightlist
\item
  \texttt{F} is a function handle to the function minimised;
\item
  \texttt{P0} is a 1-by-N vector of initial parameter values;
\item
  \texttt{PLow} is a 1-by-N vector of lower bounds (with \texttt{-Inf}
  indicating no lower bound);
\item
  \texttt{PHigh} is a 1-by-N vector of upper bounds (with \texttt{Inf}
  indicating no upper bounds);
\item
  \texttt{OptimSet} is a cell array with name-value pairs entered by the
  user through the option
  \texttt{\textquotesingle{}optimSet=\textquotesingle{}}. This option
  can be used to modify various settings related to the optimization
  routine, such as tolerance, number of iterations, etc. Of course, you
  may simply ignore it and leave this input argument unused;
\end{itemize}

and the following output arguments:

\begin{itemize}
\tightlist
\item
  \texttt{PEst} is a 1-by-N vector of estimated parameters;
\item
  \texttt{ObjEst} is the value of the objective function at optimum;
\item
  \texttt{Hess} is a N-by-N approximate Hessian matrix at optimum.
\end{itemize}

If you need to use extra input arguments in your minimization function,
enter a cell array instead of a plain function handle:

\begin{verbatim}
{@yourminfunc,Arg1,Arg2,...}
\end{verbatim}

In that case, the optimiser will be called the following way:

\begin{verbatim}
[PEst,ObjEst,Hess] = yourminfunc(F,P0,PLow,PHigh,Opt,Arg1,Arg2,...)
\end{verbatim}

\subparagraph{User-supplied steady-state
solver}

You can supply a function handle to your own steady-state solver (i.e.~a
function that finds the steady state for given parameters) through the
\texttt{\textquotesingle{}sstate=\textquotesingle{}} option.

The function is expected to take one input argument, the model object
with newly assigned parameters, and return at least two output
arguments, the model object with a new steady state (or balanced-growth
path) and a success flag. The flag is \texttt{true} if the steady state
has been successfully computed, and \texttt{false} if not:

\begin{verbatim}
[M,Success] = mysstatesolver(M)
\end{verbatim}

It is your responsibility to add the growth characteristics if some of
the model variables drift over time. In other words, you need to take
care of the imaginary parts of the steady state values in the model
object returned by the solver.

Alternatively, you can also run the steady-state solver with extra input
arguments (with the model object still being the first input argument).
In that case, you need to set the option
\texttt{\textquotesingle{}sstate=\textquotesingle{}} to a cell array
with the function handle in the first cell, and the other input
arguments afterwards, e.g.

\begin{verbatim}
'sstate=',{@mysstatesolver,1,'a',X}
\end{verbatim}

The actual function call will have the following form:

\begin{verbatim}
[M,Success] = mysstatesolver(M,1,'a',X)
\end{verbatim}

\paragraph{Example}


